Xi-Language Reference: Import and Export of Images

    • read_bmp (reads Microsoft Windows or OS/2 BMP file)
    • read_gif (reads a GIF file )
    • read_jpeg (reads a JPEG file)
    • read_pnm (reads PPM, PBM and PGM files )
    • read_targa (reads a TrueVision Targa file)
    • read_tiff (reads a TIFF file)
    • write_bmp (produces Microsoft Windows or OS/2 BMP file)
    • write_gif (produces a GIF file)
    • write_jpeg (produces a JPEG file)
    • write_pbm (produces a PBM file)
    • write_pgm (produces a PGM file)
    • write_ppm (produces a PPM file)
    • write_targa (produces a TrueVision Targa file)
    • write_tiff (produces a TIFF file)

    read_bmp (reads Microsoft Windows or OS/2 BMP file)

    Parameters

              read_bmp ( filename )
    
              Types: filename               string
    

    Return

              char[]  (contains the image, RGB color system)
    

    Description

    The function read_bmp reads a Microsoft Windows or OS/2 BMP file as input. The return value contains the image encoded in the RGB color system. It's size is [rows, columns, 3].

    Example

    test.bmp should be an image with 300 rows and 200 columns.
    >image=read_bmp("test.bmp");
    >print(size(image));
    <intarr>
        5      3 180000    300    200      3
    

    See also

    write_bmp

    Reference

    This function is based on the file bmptoppm.c of the netpbm tools.
     *
     * Copyright (C) 1992 by David W. Sanderson.
     *
    

    read_gif (reads a GIF file )

    Parameters

              read_gif ( filename )
    
              Types: filename               string
    

    Return

              char[]  (contains the image, RGB color system)
    

    Description

    The function read_gif reads a GIF file as input. The return value contains the image encoded in the RGB color system. It's size is [rows, columns, 3].

    Example

    test.gif should be an image with 300 rows and 200 columns.
    >image=read_gif("test.gif");
    >print(size(image));
    <intarr>
        5      3 180000    300    200      3
    

    See also

    write_gif

    Reference

    We are required to state that "The Graphics Interchange Format(c)" is the Copyright property of CompuServe Incorporated. This function is based on the file giftopnm.c of the netpbm tools.
    +-------------------------------------------------------------------+ 
    | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    | 
     +-------------------------------------------------------------------+ 
    

    read_jpeg (reads a JPEG file)

    Parameters

              read_jpeg ( filename )
    
              Types: filename               string
    

    Return

              char[]  (contains the image, RGB color system)
    

    Description

    The function read_jpeg reads a JPEG file as input. The return value contains the image encoded in the RGB color system. It's size is [rows, columns, 3].

    Example

    >image=read_jpeg("test.gif");
    >print(size(image));
    <intarr>
        5      3 180000    300    200      3
    

    See also

    write_jpeg

    Reference

    This function is based in part on the work of the Independent JPEG Group. Get the original libjpeg from ftp.uu.net if you need docs for the JPEG library.

    read_pnm (reads PPM, PBM and PGM files )

    Parameters

              read_pnm ( filename )
    
              Types: filename               string
    

    Return

              char[]  (contains the image, RGB color system)
    

    Description

    The function read_pnm reads PPM, PBM and PGM files as input. The return value contains the image encoded in the RGB color system. It's size is [rows, cols, 3].

    Example

    test.ppm, test.pgm and test.pbm should be images with 300
    rows and 200 columns.
    >image1=read_pnm("test.ppm");
    >image2=read_pnm("test.pgm");
    >image3=read_pnm("test.pbm");
    >print(size(image1));
    <intarr>;
        5      3 180000    300    200      3
    

    See also

    write_ppm, write_pgm, write_pbm

    Reference

    This function is based on the function ppm_readppm of the file libppm1.c of the netpbm tools.
     **
     ** Copyright (C) 1989 by Jef Poskanzer.
     **
    

    read_targa (reads a TrueVision Targa file)

    Parameters

              read_targa ( filename )
    
              Types: filename               string
    

    Return

              char[]  (contains the image, RGB color system)
    

    Example

    test.tga should be images with 300
    rows and 200 columns.
    >image=read_targa("test.tga");
    >print(size(image1));
    <intarr>
        5      3 180000    300    200      3
    

    read_tiff (reads a TIFF file)

    Parameters

              read_tiff ( filename )
    
              Types: filename               string
    

    Return

              char[]  (contains the image, RGB color system)
    

    Description

    The function read_tiff reads a TIFF file as input. The return value contains the image encoded in the RGB color system. It's size is [rows, columns, 3].

    Example

    test.tiff should be images with 300
    rows and 200 columns.
    >image=read_tiff("test.tga");
    >print(size(image1));
    <intarr>
        5      3 180000    300    200      3
    

    See also

    write_tiff

    Reference

    This function is based on the file tifftopnm.c of the netpbm tools. Derived by Jef Poskanzer from tif2ras.c, which is:
     ** Copyright (c) 1990 by Sun Microsystems, Inc.
     **
     ** Author: Patrick J. Naughton
     ** naughton@wind.sun.com
     **
     ** This file is provided AS IS with no warranties of any kind.  The author
     ** shall have no liability with respect to the infringement of copyrights,
     ** trade secrets or any patents by this file or any part thereof.  In no
     ** event will the author be liable for any lost revenue or profits or
     ** other special, indirect and consequential damages.
    
    Other files of the library libtiff have the follwing copyright note
    
     * Copyright (c) 1988, 1989, 1990, 1991, 1992 Sam Leffler
     * Copyright (c) 1991, 1992 Silicon Graphics, Inc.
     *
     * ....(ii) the names of
     * Sam Leffler and Silicon Graphics may not be used in any advertising or
     * publicity relating to the software without the specific, prior written
     * permission of Sam Leffler and Silicon Graphics.
    

    write_bmp (produces Microsoft Windows or OS/2 BMP file)

    Parameters

              write_bmp ( filename, image, colormap = 0, os2 )
    
              Types: filename               string
                     image                  char[]
                     colormap               char[]
                     os2                    int
    

    Return

              -1
    

    Description

    The function write_bmp produces a Microsoft Windows or OS/2 BMP file as output. The array image contains the image. If image is a two dimensional array a colormap based image is assumed and you have to specify the colormap with the parameter \colormap. A colormap is senseless if image contains a RGB encoded image. In this case image has three dimensions with the ranges [rows, columns, 3]. The flag \os2 tells the function to produce an OS/2 BMP file.

    Example

    >image=cincarr(5,5,3);
    >write_bmp("test.bmp",image,\os2);
    >[pixmap, colormap]=rgb2map(image);
    >write_bmp("test.bmp",pixmap, colormap,\os2);
    

    See also

    read_bmp

    Reference

    This function is based on the file ppmtobmp.c of the netpbm tools.
     *
     * Copyright (C) 1992 by David W. Sanderson.
     *
    

    write_gif (produces a GIF file)

    Parameters

              write_gif ( filename, image, colormap = 0, interlace = 0, 
                          transparent = {0,0,0} , unsorted = 0 )
    
              Types: filename               string
                     image                  char[]
                     colormap               char[]
                     interlace              int
                     transparent            char[]
                     unsorted               int
    

    Return

              -1
    

    Description

    The function write_gif produces a GIF file as output. The array image contains the image. If image is a two dimensional array a colormap based image is assumed and you have to specify the colormap with the parameter \colormap. A colormap is senseless if image stands for a RGB encoded image. In this case image has three dimensions with the ranges [rows, columns, 3]. The flag \interlace tells the function to produce an interlaced GIF file. The parameter transparent marks the given color (RGB system) as transparent in the GIF file. Finally this function generates a sorted color map by default. Change this behavior by setting the flag unsorted.

    Example

    >image=cincarr(5,5,3);
    >write_gif("test.gif",image);
    >[pixmap, colormap]=rgb2map(image);
    >write_gif("test.gif",pixmap, colormap);
    >write_gif("test.gif",\transparent={0,0,1});
    

    See also

    read_gif

    Reference

    We are required to state that "The Graphics Interchange Format(c)" is the Copyright property of CompuServe Incorporated. This function is based on the file ppmtogif.c of the netpbm tools.
     *
     * Copyright (C) 1992 by David W. Sanderson.
     *
    

    write_jpeg (produces a JPEG file)

    Parameters

              write_jpeg ( filename, image, colormap = 0, quality = 9 )
    
              Types: filename               string
                     image                  char[]
                     colormap               char[]
                     quality                int
    

    Return

              -1
    

    Description

    The function write_jpeg produces a JPEG file as output. The array image contains the image. If image is a two dimensional array a colormap based image is assumed and you have to specify the colormap with the parameter \colormap. A colormap is senseless if image contains a RGB encoded image. In this case image has three dimensions with the ranges [rows, columns, 3]. The parameter quality controls the quality (and the storage consumption) of the image.

    Example

    >image=cincarr(50,50,3);
    >write_jpeg("test.jpg",image);
    >$ls -l test.jpg
    -rw-r--r--   1 spander  scratch      1035 May 13 08:53 test.jpg
    >write_jpeg("test.jpg",image,\quality=100);
    >$ls -l test.jpg
    -rw-r--r--   1 spander  scratch      4234 May 13 08:54 test.jpg
    

    See also

    read_jpeg

    Reference

    This function is based in part on the work of the Independent JPEG Group. Get the original libjpeg from ftp.uu.net if you need docs for the JPEG library.

    write_pbm (produces a PBM file)

    Parameters

              write_pbm ( filename, image, bin )
    
              Types: filename               string
                     image                  char[]
                     bin                    int
    

    Return

              -1
    

    Description

    The function write_pbm produces a PBM file as output. The array image contains the image. This image has to be a two dimensional array because the PBM format is a common denominator monochrome file format. By default the data is stored in ASCII decimal. The parameter bin tells the function to store the pixels as plain bytes instead of ASCII decimal.

    Example

    >image=carr(50,50);
    >image[*,4]=1;
    >write_pbm("test.pbm",image);
    

    See also

    read_pnm

    write_pgm (produces a PGM file)

    Parameters

              write_pgm ( filename, image, bin )
    
              Types: filename               string
                     image                  char[]
                     bin                    int
    

    Return

              -1
    

    Description

    The function write_pgm produces a PGM file as output. The array image contains the image. It has to be a two dimensional array because the PGM format is a common grayscale file format. By default the data is stored in ASCII decimal. The parameter bin tells the function to store the pixels as plain bytes instead of ASCII decimal.

    Example

    >image=cincarr(50,50);
    >write_pgm("test.pgm",image);
    

    See also

    read_pnm

    write_ppm (produces a PPM file)

    Parameters

              write_ppm ( filename, image, colormap = 0, bin )
    
              Types: filename               string
                     image                  char[]
                     colormap               char[]
                     bin                    int
    

    Return

              -1
    

    Description

    The function write_ppm produces a PPM file as output. The array image contains the image. If image is a two dimensional array then a colormap based image is assumed and you have to specify the colormap with the parameter \colormap. A colormap is senseless if image contains a RGB encoded image. In this case image has three dimensions with the ranges [rows, cols, 3]. By default the data is stored in ASCII decimal. The parameter bin tells the function to store the pixels as plain bytes instead of ASCII decimal.

    Example

    >image=cincarr(5,5,3);
    >write_ppm("test.ppm",image);
    >[pixmap, colormap]=rgb2map(image);
    >write_ppm("test.ppm",pixmap, colormap);
    

    See also

    read_pnm

    write_targa (produces a TrueVision Targa file)

    Parameters

              write_targa ( filename, image, colormap = 0, mono = 0, 
                            cmap = 0, rgb = 0, norle = 0 )
    
              Types: filename               string
                     image                  char[]
                     colormap               char[]
                     mono                   int
                     cmap                   int
                     rgb                    int
                     norle                  int
    

    Return

              -1
    

    Description

    The function write_targa produces a TrueVision Targa file as output. The array image contains the image. If image is a two dimensional array then a colormap based image is assumed and you have to specify the colormap with the parameter \colormap. A colormap is senseless if image contains a RGB encoded image. In this case image has three dimensions with the ranges [rows, columns, 3]. If the image is a colormap based image and the parameter mono is set then the Targa file is of type 8 bit monochrome. The Flag \cmap forces the Targa file to be of type 24 bit colormapped whereas \rgb forces Targa file to be of type 24 bit unmapped color. The parameter norle disables run-length encoding.

    Example

    >image=cincarr(5,5,3);
    >write_targa("test.tga",image);
    >write_targa("test.tga",image,\rgb,\norle);
    >[pixmap, colormap]=rgb2map(image);
    >write_targa("test.tga",pixmap, colormap,\mono);
    

    See also

    read_targa

    Reference

    This function is based on the file ppmtotga.c of the netpbm tools.
     **
     ** Partially based on tga2rast, version 1.0, by Ian MacPhedran.
     **
     ** Copyright (C) 1989 by Jef Poskanzer.
     **
    

    write_tiff (produces a TIFF file)

    Parameters

              write_tiff ( filename, image, colormap = 0, none = 0, 
                           packbits = 0, lzw = 1, fax3 = 0, fax4 = 0, 
                           fill_msb2lsb = 0, fill_lsb2msb = 0, d2 = 0, 
                           fill = 0  )
    
              Types: filename               string
                     image                  char[]
                     colormap               char[]
                     none                   int
                     packbits               int
                     lzw                    int
                     fax3                   int
                     fax4                   int
                     fill_msb2lsb           int
                     fill_lsb2msb           int
                     d2                     int
                     fill                   int
    

    Return

              -1
    

    Description

    The function write_tiff produces a TIFF file as output. The array image contains the image. If image is a two dimensional array a colormap based image is assumed and you have to specify the colormap with the parameter \colormap. A colormap is senseless if image contains a RGB encoded image. In this case image has three dimensions with the ranges [rows, columns, 3]. The flags none, packbits, lzw, fax3 and fax4 are used to override the default (LZW compression) and to set the compression scheme used in creating the output file. The CCITT Group 3 (fax3) and Group 4 (fax4) compression algorithms can only be used with bilevel data (bilevel images consist of 0 and 1 only). The d2 and fill options are meaningful only with Group 3 compression: d2 requests 2-dimensional encoding, while fill requests that each encoded scanline be zero-filled to a byte boundry. By default this functions creates a TIFF file with msb-to-lsb fill order. The msb2lsb and lsb2msb options are used to override the default and to set the fill order used in creating the file.

    Example

    >image=cincarr(5,5,3);
    >write_tiff("test.tiff",image);
    >write_tiff("test.tiff",image,\packbits);
    >pixmap=rgb2map(color_reduce(image,\colors=2,\floyd));
    >colormap={ {0,0,0}, {1,1,1} };
    >write_tiff("test.tiff",pixmap, colormap,\fax3,\fill);
    

    See also

    read_tiff

    Reference

    This function is based on the file tifftopnm.c of the netpbm tools. Derived by Jef Poskanzer from ras2tif.c, which is:
     ** Copyright (c) 1990 by Sun Microsystems, Inc.
     **
     ** Author: Patrick J. Naughton
     ** naughton@wind.sun.com
     **
     ** This file is provided AS IS with no warranties of any kind.  The author
     ** shall have no liability with respect to the infringement of copyrights,
     ** trade secrets or any patents by this file or any part thereof.  In no
     ** event will the author be liable for any lost revenue or profits or
     ** other special, indirect and consequential damages.
    
    Other files of the library libtiff have the follwing copyright note
     * Copyright (c) 1988, 1989, 1990, 1991, 1992 Sam Leffler
     * Copyright (c) 1991, 1992 Silicon Graphics, Inc.
     *
     * ....(ii) the names of
     * Sam Leffler and Silicon Graphics may not be used in any advertising or
     * publicity relating to the software without the specific, prior written
     * permission of Sam Leffler and Silicon Graphics.
    

    © 1995 by Bodo Junglas, Klaus Spanderen and Fabian Weis
    - Last revised: Wed Jun 19 16:58:32 1996